Agent Sessions

A session is one continuous conversation with a coding agent: every message, every file edit, every tool call, plus the branch and commit it produced. The CLI captures sessions in the background — you don’t bb start anything — and lets you resume them later, on any machine, by anyone on your team with access to the repo. This is what makes bb agent-sessions resume feel like time travel.

How capture works

The moment bb is installed, it watches the on-disk session log of every supported coding agent:

Agent	Source it tails
Claude Code	`~/.claude/projects/<repo>/sessions/*.jsonl`
Codex CLI	`~/.codex/sessions/*.jsonl`
Cursor	Cursor’s local SQLite + workspaceStorage logs
Copilot CLI	`~/.config/github-copilot/cli/sessions/`
Gemini CLI	`~/.gemini/sessions/`
Windsurf	Windsurf workspace storage
Amazon Q	`~/.aws/q/sessions/`

Whenever an agent writes to its log, bb indexes the new turns, attaches the current git state (repo, branch, HEAD commit, dirty paths), and writes a normalized session record to ~/.buildbetter/sessions/. If you’re signed in (bb login), the record syncs to your free BuildBetter workspace within a few seconds.

Capture is passive. There’s no daemon to start, nothing to remember, no flag to set on the agent. Install the CLI once and every session from then on is captured.

Where sessions are stored

~/.buildbetter/
├── bin/bb
├── config.toml
├── sessions/
│   ├── index.db                      # SQLite — fast lookup by repo/branch/commit
│   ├── 2026/05/07/
│   │   ├── ee7f3a-codex.session.json # one file per session
│   │   └── 1f2c8d-claude.session.json
│   └── pending/                      # awaiting sync to the cloud
└── logs/bb.log

Each .session.json is a self-contained record:

{
  "id": "ee7f3a",
  "agent": "codex",
  "repo": "buildbetter-app/bbapp",
  "branch": "codex/llm-data-source",
  "commit": "9f3a1c2",
  "author": "spencer@buildbetter.app",
  "started_at": "2026-05-07T10:14:33Z",
  "ended_at": "2026-05-07T12:08:51Z",
  "messages": 247,
  "file_edits": 12,
  "tool_calls": 38,
  "summary": "Ingest LLM chat history as a new data source...",
  "open_questions": [
    "Should agent_logs be its own model or stay on conversation?"
  ],
  "linked_pr": 3308
}

The full transcript lives next to the metadata (or in the cloud, depending on size). Source code is not copied — bb only stores the file paths and diffs the agent touched.

Resuming a session

The most common call:

bb agent-sessions resume

The CLI lists sessions tied to the current branch (yours and your team’s), most recent first, and hydrates the chosen one into your active agent:

? Resume which session?
❯ codex/llm-data-source · spencer · 2h ago    · 247 msgs
  bb-recorder-pass-through · nikhil · 3d ago  · 89 msgs
  websocket-rpc-stream · spencer · 6d ago     · 312 msgs

✓ Hydrating session ee7f3a — 247 messages, 12 file edits

Codex › Picking up Spencer's exec plan for LLM ingestion.
Last open question was the conversation/agent_logs split.
> _

What “hydrate” actually does:

Loads the prior conversation into the agent’s context window (compacted if it’s long)
Replays the file edits as a virtual diff so the agent knows what it changed
Surfaces the open questions the prior session left behind — not just a transcript, but a state you can keep working from

Resume by ID

If you already know the session you want — say it’s linked from a PR comment or a teammate sent it to you:

bb agent-sessions resume ee7f3a

Resume on a branch you didn’t start

You don’t need to be the original author. The picker shows everyone’s sessions for the current branch, and resuming pulls the conversation into your agent on your machine:

git checkout nikhil/payments-stripe-webhook
bb agent-sessions resume

This is the “no copy-paste handoff” flow — see the Branch handoff workflow below.

Searching across sessions

Resume is for the current branch. When you need to find a session from somewhere else — a PR you reviewed last month, a feature whose name you forgot — search:

bb agent-sessions search "agent_logs"               # full-text across all sessions
bb agent-sessions list --author maya --since 30d    # everything Maya did this month
bb agent-sessions list --branch "feat/exports"      # by branch
bb agent-sessions show ee7f3a                       # full metadata + summary

Output supports --json if you want to pipe it into something:

bb agent-sessions search "OAuth" --json | jq '.[].id'

PR linking

When you push a branch and open a PR, bb auto-attaches the session(s) that produced it. Reviewers can pull the chat to understand why the code looks the way it does — better than the PR description, and impossible to lose to a closed tab.

bb agent-sessions link 3308          # manually link the current session to PR #3308
bb agent-sessions show ee7f3a        # see which PR a session is linked to

To disable auto-linking for a specific repo:

bb config set pr.auto_link false

Workflows

Workflow: branch handoff

Spencer started a feature, has to step away. Maya picks it up.

# Spencer (Monday, EOD)
git push -u origin spencer/llm-data-source
# bb auto-syncs the session as a side effect of normal coding

# Maya (Tuesday morning, on her laptop)
git fetch && git checkout spencer/llm-data-source
bb agent-sessions resume
# > picks Spencer's session · 247 msgs · 2h ago
# Codex hydrates with everything Spencer worked through, including the
# open question he left for her.

No Slack screenshots. No “wait, what were you trying to do?” The agent already knows.

Workflow: post-merge context recovery

Six months later, a customer ticket lands on a system someone else built.

git log -- src/agent_logs            # find the commit / PR
git checkout <commit>                # check out the historical state
bb agent-sessions list --branch HEAD # see every session that touched this code
bb agent-sessions resume <id>        # pull the chat that produced it

The agent loads the original reasoning — including any decisions the PR description never mentioned (“we picked denormalized to keep report queries under 50ms”).

Workflow: ticket → spec → PR loop

The full close-the-loop play with skills + sessions:

# 1. Customer ticket #4127 lands. Pull it into a spec with team conventions.
/bb-specify "CSV export fails for orgs > 10k rows — see ticket #4127"

# 2. Plan and implement against the spec.
/bb-plan
/bb-implement

# 3. Verify in a real browser before merging.
/trust-but-verify

# 4. Push. Session auto-attaches to the PR for reviewers.
git push -u origin fix/large-csv-export

# 5. Months later, when the next ticket hits this code:
bb agent-sessions resume   # the chat that produced this code is right here

Workflow: scripting in a pre-commit hook

Make sure every commit has an attached session, so the chat is never lost:

# .git/hooks/pre-commit
test -n "$(bb agent-sessions list --branch HEAD --since 1d --json | jq '.[0]')" \
  || { echo "No active agent session — run an agent or bb agent-sessions link"; exit 1; }

Privacy & access

What’s stored	Where	Who can see it
Chat messages, tool calls, file paths, diffs, branch metadata	Your free BuildBetter workspace, encrypted in transit and at rest	Anyone with access to the same repo in your workspace
Source code	Never copied — only paths and diffs	n/a
Sessions before `bb login`	`~/.buildbetter/sessions/` on your machine	You only
Sessions in a repo nobody else has access to	Same as above	You only

To delete:

bb agent-sessions delete <session-id>     # one session
bb agent-sessions purge --repo .          # everything for the current repo
bb agent-sessions purge --before 90d      # everything older than 90 days

To opt a sensitive repo out of cloud sync entirely:

cd path/to/sensitive-repo
bb config set sync.enabled false

To exclude specific branches from being captured at all:

bb config set sessions.exclude_branches "secret/*,scratch/*"

Working offline

If you skip bb login, capture still works — sessions land in ~/.buildbetter/sessions/ and you can resume your own sessions on the same machine. You just lose cross-machine sync and teammate-resumable sessions. Sign in any time and the local backlog back-fills the cloud index.

bb sync --status   # see how many local sessions are pending sync
bb sync            # force the back-fill now

Next steps

CLI reference

Every bb command in one place

Skills

The slash commands that work alongside session resume

Getting Started

Using the CLI

Agent Sessions

Agent Sessions

How capture works

Where sessions are stored

Resuming a session

Resume by ID

Resume on a branch you didn’t start

Searching across sessions

PR linking

Workflows

Workflow: branch handoff

Workflow: post-merge context recovery

Workflow: ticket → spec → PR loop

Workflow: scripting in a pre-commit hook

Privacy & access

Working offline

Next steps

CLI reference

Skills

Getting Started

Using the CLI

Documentation Index

​Agent Sessions

​How capture works

​Where sessions are stored

​Resuming a session

​Resume by ID

​Resume on a branch you didn’t start

​Searching across sessions

​PR linking

​Workflows

​Workflow: branch handoff

​Workflow: post-merge context recovery

​Workflow: ticket → spec → PR loop

​Workflow: scripting in a pre-commit hook

​Privacy & access

​Working offline

​Next steps

CLI reference

Skills

Agent Sessions

How capture works

Where sessions are stored

Resuming a session

Resume by ID

Resume on a branch you didn’t start

Searching across sessions

PR linking

Workflows

Workflow: branch handoff

Workflow: post-merge context recovery

Workflow: ticket → spec → PR loop

Workflow: scripting in a pre-commit hook

Privacy & access

Working offline

Next steps